Gitea Action Runner 物理机部署

  • ~7.57K 字
  1. 1. 一、部署前准备
  2. 2. 二、下载并校验 Runner
  3. 3. 三、创建运行用户与配置
    1. 3.1. 标签与执行环境
  4. 4. 四、获取令牌并注册
  5. 5. 五、配置 systemd 服务
  6. 6. 六、运行工作流验证
  7. 7. 七、日常管理与排错
    1. 7.1. 服务启动失败或 Runner 离线
    2. 7.2. 作业一直等待
    3. 7.3. 注册成功,但检出代码失败
    4. 7.4. 拉取镜像失败或提示 exec format error
  8. 8. 参考资料

本文使用官方二进制在 Linux 上安装 Gitea Actions Runner,由 systemd 管理进程,默认通过 Docker 容器执行作业。适用于 AMD64 / ARM64 主机,示例固定使用 5.4.1,不自动追踪最新版本。

“物理机部署”指 Runner 进程直接运行在宿主机上;作业是否在宿主机执行,由 Runner 的标签决定。本文也适用于 Linux 虚拟机。

本文用于首次安装。已有 Runner 请参考 Gitea Action Runner 升级,不要直接覆盖现有配置或重复注册。旧教程中的 act_runner 与本文的 gitea-runner 名称和命令可能不同,请以目标版本的帮助信息为准。

一、部署前准备

按 Runner 5.x 官方要求,部署前确认:

  • Gitea 为 1.21 或更高版本,且已启用 Actions;需要运行工作流的仓库也应启用 Actions。
  • Runner 主机已安装 Git 2.34.1 或更高版本,以及正在运行的 Docker Engine。
  • Runner 主机与作业容器均能访问 Gitea 的对外地址;还需能下载作业镜像和工作流使用的 Action。
  • 安装命令在 root 的 Bash 会话中执行;服务使用单独的 gitea-runner 用户运行。

Debian / Ubuntu 可先安装基础工具,Docker 请按 Docker 官方安装文档单独安装:

sudo -i
apt-get update
apt-get install -y ca-certificates wget xz-utils coreutils git

# Git 版本必须满足要求
git --version
systemctl enable --now docker
docker info

其他发行版请使用对应的包管理器,后续命令仍在 root 的 Bash 会话中执行。

二、下载并校验 Runner

将以下内容保存为 install-gitea-runner.sh。脚本识别 CPU 架构,下载官方压缩包及 SHA256 文件,校验成功后才安装。

#!/usr/bin/env bash
set -euo pipefail

VERSION="5.4.1"
INSTALL_PATH="/usr/local/bin/gitea-runner"

if [[ $EUID -ne 0 ]]; then
    echo '请使用 root 运行'
    exit 1
fi

# 首次安装不覆盖已有程序;升级请使用升级流程。
if [[ -e "$INSTALL_PATH" ]]; then
    echo "程序已存在:$INSTALL_PATH,请改用升级流程"
    exit 1
fi

case "$(uname -m)" in
    x86_64|amd64) ARCH="amd64" ;;
    aarch64|arm64) ARCH="arm64" ;;
    *) echo "不支持的架构:$(uname -m)"; exit 1 ;;
esac

BINARY_NAME="gitea-runner-${VERSION}-linux-${ARCH}"
DOWNLOAD_URL="https://dl.gitea.com/gitea-runner/${VERSION}/${BINARY_NAME}.xz"
TMP_DIR="$(mktemp -d)"
trap 'rm -rf -- "$TMP_DIR"' EXIT
cd "$TMP_DIR"

wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz" "$DOWNLOAD_URL"
wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz.sha256" "${DOWNLOAD_URL}.sha256"
sha256sum -c "${BINARY_NAME}.xz.sha256"
xz -d "${BINARY_NAME}.xz"
install -m 0755 "$BINARY_NAME" "$INSTALL_PATH"
"$INSTALL_PATH" --version

执行安装:

bash install-gitea-runner.sh

预期输出包含校验 OK 和 5.4.1 版本信息。下载失败时,先检查 5.4.1 官方文件目录中的文件名、架构和版本;校验失败不要继续安装。

三、创建运行用户与配置

将配置与运行数据分开存放,路径约定如下:

路径 用途
/usr/local/bin/gitea-runner 可执行文件
/etc/gitea-runner/config.yaml Runner 配置
/var/lib/gitea-runner/ 服务工作目录、用户主目录
/var/lib/gitea-runner/.runner 注册信息,包含凭据
/etc/systemd/system/gitea-runner.service systemd 服务

首次安装时执行:

useradd --system --user-group --home-dir /var/lib/gitea-runner \
    --create-home --shell /usr/sbin/nologin gitea-runner
usermod -aG docker gitea-runner
chmod 0700 /var/lib/gitea-runner
install -d -m 0750 -o root -g gitea-runner /etc/gitea-runner

# 生成当前版本的配置参考,不覆盖正式配置
gitea-runner config generate > /etc/gitea-runner/config.example.yaml

加入 docker 组可以操作 Docker socket,实际上具有宿主机 root 级能力。请在专用 CI 主机上运行可信仓库的作业;使用专用用户并不代表 Docker 作业具有完整的安全隔离。

创建本文使用的最小配置:

cat > /etc/gitea-runner/config.yaml <<'EOF'
log:
  level: info

runner:
  file: /var/lib/gitea-runner/.runner
  capacity: 1
  timeout: 3h
  shutdown_timeout: 30s
  labels:
    - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
EOF

chown root:gitea-runner /etc/gitea-runner/config.yaml
chmod 0640 /etc/gitea-runner/config.yaml

# 确认服务用户可以访问 Docker
sudo -u gitea-runner -H docker info

其余选项使用 Runner 默认值;完整说明见生成的参考文件和配置文档。capacity: 1 表示同时执行一个作业。停止服务时,shutdown_timeout: 30s 允许正在执行的作业继续运行最多 30 秒,超时后取消。

标签与执行环境

本文的标签映射为:

ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
└─ runs-on 名称       └─ 作业容器镜像

工作流写 runs-on: ubuntu-latest,作业就使用该镜像。它不会把宿主机变成 Ubuntu,也不要求宿主机必须是 Ubuntu。ARM64 主机需要确认所选镜像及工作流依赖支持 ARM64。

如果确实需要直接在宿主机执行作业,可将 runner.labels 改为 linux-host:host,工作流相应写 runs-on: linux-host。此时需要在宿主机准备 Bash、Git、Node.js 及构建工具,作业以服务用户身份执行,没有容器隔离。仅运行 host 作业且不使用 Docker Action 时可省略 Docker,并移除后文服务中的 Docker 依赖。

标签的详细规则见官方标签文档。修改配置后需要重启服务生效,不需要重新注册。

四、获取令牌并注册

在 Gitea 中按用途选择 Runner 范围:仓库、组织或整个实例。个人仓库优先使用仓库级 Runner,避免接受无关仓库的任务。

进入对应范围的 设置 → Actions → Runners 获取注册令牌;实例级入口位于站点管理中,具体位置随 Gitea 版本可能略有差异。这里需要的是 Runner 注册令牌,不是个人访问令牌(PAT)。参考 Gitea 的 Runner 管理说明。

在工作目录中,以服务用户交互式注册:

cd /var/lib/gitea-runner
sudo -u gitea-runner -H /usr/local/bin/gitea-runner \
    --config /etc/gitea-runner/config.yaml register

按提示填写:

项目 示例或说明
Gitea 地址 https://gitea.example.com/,替换为实际实例的 ROOT_URL
注册令牌 从对应范围的 Runner 设置页复制
Runner 名称 如 linux-runner-01,便于区分主机
标签 本文已在配置中指定,通常不会再询问

不要使用 localhost 或 127.0.0.1 作为 Gitea 地址:它们在作业容器中指向容器自身。注册地址应能从宿主机和作业容器访问。

注册成功后检查文件权限,不要输出文件内容:

chmod 0600 /var/lib/gitea-runner/.runner
ls -l /var/lib/gitea-runner/.runner

.runner 保存身份凭据,应持久保存且不要提交到 Git。日常重启无需再次注册;注册文件丢失时才需要重新注册,并清理 Gitea 中失效的旧 Runner 记录。详见官方注册文档。

五、配置 systemd 服务

本文使用本机 Docker Engine,服务同时声明 Docker 启动顺序和依赖:

cat > /etc/systemd/system/gitea-runner.service <<'EOF'
[Unit]
Description=Gitea Actions Runner
Documentation=https://docs.gitea.com/runner/
Wants=network-online.target
After=network-online.target docker.service
Requires=docker.service

[Service]
Type=simple
User=gitea-runner
Group=gitea-runner
WorkingDirectory=/var/lib/gitea-runner
Environment=HOME=/var/lib/gitea-runner
ExecStart=/usr/local/bin/gitea-runner daemon --config /etc/gitea-runner/config.yaml
Restart=on-failure
RestartSec=10s
TimeoutStopSec=60s
UMask=0077

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now gitea-runner
systemctl status gitea-runner --no-pager
journalctl -u gitea-runner -n 50 --no-pager

TimeoutStopSec 大于配置中的 shutdown_timeout,为 Runner 退出预留时间。后续如延长作业等待时间,应同步调整两处数值。配置只在启动时读取,修改后执行 systemctl restart gitea-runner;这里不配置未经确认支持的 HUP 重载。

六、运行工作流验证

先在 Gitea 对应的 Runner 页面确认它已在线、标签包含 ubuntu-latest,再在测试仓库创建 .gitea/workflows/runner-check.yaml:

name: Runner Check
on: [push]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: https://github.com/actions/checkout@v4
      - name: Check environment
        run: |
          uname -m
          git --version
          node --version
          git rev-parse --short HEAD
          echo "Runner is ready"

提交并推送到测试仓库后,在 Actions 页面检查作业是否成功。首次执行需要下载镜像和 Checkout Action,因此主机需要相应的网络访问能力;示例使用显式 GitHub 地址。

以下三项均通过,才能确认部署可用:

  1. systemd 服务处于 active。
  2. Gitea 页面中 Runner 在线且标签正确。
  3. 工作流能检出代码、执行命令,并回传日志及成功状态。

七、日常管理与排错

# 查看服务状态和实时日志
systemctl status gitea-runner --no-pager
journalctl -u gitea-runner -f

# 修改配置后重启;操作前确认没有正在执行的重要任务
systemctl restart gitea-runner

# 停止服务 / 取消开机启动
systemctl stop gitea-runner
systemctl disable gitea-runner

服务启动失败或 Runner 离线

systemctl cat gitea-runner
journalctl -u gitea-runner -n 100 --no-pager
sudo -u gitea-runner -H test -r /etc/gitea-runner/config.yaml
sudo -u gitea-runner -H test -r /var/lib/gitea-runner/.runner
sudo -u gitea-runner -H docker info

重点检查程序路径、YAML 缩进、注册文件是否属于服务用户、Docker 是否启动,以及主机到 Gitea 的 DNS、网络与 TLS 证书。test -r 成功时没有输出,失败时返回非零状态。

若使用私有 CA,需要同时解决宿主机和作业镜像的证书信任;不要把关闭 TLS 校验当作常规修复。systemd 服务也不会自动继承当前终端的代理变量,需要时在服务中单独设置环境变量,并区分 Runner、Docker daemon 和作业容器各自的代理配置。

作业一直等待

检查仓库是否启用 Actions、Runner 的注册范围是否覆盖该仓库、runs-on 是否匹配标签,以及唯一的并发槽位是否被其他任务占用。仅看到服务 active,不能证明 Runner 已成功连接 Gitea。

注册成功,但检出代码失败

注册只证明 Runner 进程能访问 Gitea;Checkout 在作业环境中执行。检查 Gitea 对外地址是否能从容器解析和访问,避免使用本机回环地址,同时核对容器的 CA 证书和网络设置。

拉取镜像失败或提示 exec format error

前者优先检查 Docker daemon 到镜像仓库的网络、认证与代理;后者检查 Runner 二进制、作业镜像和下载工具的 CPU 架构是否与主机一致。ARM64 主机不能仅因为标签叫 ubuntu-latest 就假定能运行只支持 AMD64 的工具。

参考资料